.Dd June 29, 2017
.Dt GITSH 1
.Os
.Sh NAME
.Nm gitsh
.Nd Interactive shell for the git version control system
.
.Sh SYNOPSIS
.Nm gitsh
.Op Fl -version
.Op Fl h
.Op Fl -git Ar CMD
.Op file
.
.Sh DESCRIPTION
.Nm gitsh
is a language for interacting with a
.Xr git 1
repository. It supports all git subcommands, custom aliases, and custom
commands for interacting with the shell itself.
.Pp
Running gitsh with no arguments will start an interactive session. Quit by
either typing
.Ic :exit
or
.Ic :q
or sending an EOF character.
.Pp
Passing the path to a file containing a series of commands or sending a series
of commands to gitsh's standard input will run each of those commands in
sequence.
.Pp
In interactive mode, commands and their arguments can be completed using tab
completion.
The rules for what can be completed are defined in configuration files;
see
.Xr gitsh_completions 5
for details.
.Pp
It supports these options and arguments:
.
.Bl -tag
.It Fl -git Ar CMD
use the git command specified in CMD, instead of the default (
.Ic /usr/bin/env git
or as specified by the
.Ic gitsh.gitCommand
configuration option
).
.It Fl h , Fl -help
display a help message and exit.
.It Fl -version
display the version number and exit.
.It Ic file
the path to a file of commands to be executed. If the path is
.Ic -
then the commands will be read from the standard input.
.El
.Pp
Within the shell you can use the following types of commands:
.Bl -tag
.It Ic command [arguments]
execute a Git command or alias with the given arguments, e.g.
.Ic status
will execute
.Xr git-status 1 .
.It Ic !command [arguments]
execute a shell command with the given arguments, e.g.
.Ic !ls
will execute
.Xr ls 1 .
.It Ic :command [arguments]
execute a built-in gitsh command. See the section on
.Sx BUILT-IN COMMANDS
for a list of supported commands.
.It Ic #comment
any input after a
.Ic #
character will be treated as comments and ignored.
.El
.Pp
Commands can be combined using the following operators, which have similar
semantics to
.Xr sh 1 :
.Bl -tag
.It Ic left && right
only execute
.Ic right
if
.Ic left
succeeds.
.It Ic left || right
only execute
.Ic right
if
.Ic left
fails.
.It Ic left\ ; right
execute
.Ic left ,
and then
.Ic right .
.El
.Pp
As in
.Xr sh 1 ,
and many other general-purpose languages,
.Ic &&
has greater precedence than
.Ic || .
That precedence can be overridden by surrounding a clause
with parentheses.
For example, the following two commands are not equivalent:
.Bd -literal -offset indent
@ :echo $first || :echo $second && :echo $third
@ (:echo $first || :echo $second) && :echo $third
.Ed
.
.Sh PROMPT
The prompt changes based on the status of the repository. By default it consist
of three parts: the basename of the current working directory, the current HEAD
and the terminator sigil.
.Pp
The current HEAD is a branch name, tag name, abbreviated SHA, or the text
.Li uninitialized
when the present working directory is not a git repository. It is limited to 15
characters.
.Pp
The state of the repository is reflected by the terminating sigil and the color
of both the current HEAD and the sigil:
.Bl -column "Untracked files" ".Sy Sigil" ".Ic gitsh.color.uninitialized" ".Sy Default" -offset indent
.It Sy Status           Ta Sy Sigil     Ta Sy Color setting                Ta Sy Default
.It Not a git repo      Ta !!           Ta Ic gitsh.color.uninitialized    Ta normal red
.It Untracked files     Ta !            Ta Ic gitsh.color.untracked        Ta red
.It Modified files      Ta &            Ta Ic gitsh.color.modified         Ta yellow
.It Default             Ta @            Ta Ic gitsh.color.default          Ta blue
.El
.Pp
.Ss Prompt customisation
The prompt can be customised by setting the
.Ic gitsh.prompt
variable using the
.Xr git-config 1
command. The following placeholders can be used in the custom prompt:
.
.Bl -column ".Sy Placeholder" ".Sy Meaning" -offset indent
.It Sy Placeholder  Ta Sy Meaning
.It %#              Ta terminating sigil (see previous table)
.It %b              Ta current HEAD (full branch name, tag name, etc.)
.It \&%B            Ta current HEAD, limited to 15 characters
.It %d              Ta absolute path to current working directory
.It \&%D            Ta basename of the current working directory
.It %g              Ta absolute path of git binary in use
.It %G              Ta basename of git binary in use
.It %c              Ta start coloring based on status (see previous table)
.It %w              Ta return to default color (e.g. after using %c)
.El
.Pp
For example, setting
.Ic gitsh.prompt
to
.Ic (%b)%d%#
would produce prompts like
.Ic (master)/home/me/repo@
and
.Ic (uninitialized)/home/me!!
.Sh BUILT-IN COMMANDS
Built-in commands are used to give instructions to the shell. To distinguish
them from git commands, and to avoid collisions with git aliases and
extensions, they are prefixed with a
.Ic :
character.
.Pp
The following commands are supported:
.Bl -tag -width Ds
.It Ic :set variable value
sets a variable in the gitsh environment to the given value.
.Bd -literal -offset indent
@ :set george "George <george@thoughtbot.com>"
@ commit --author $george
.Ed
.Pp
Variable names containing a dot can be used to temporarily override
.Xr git-config 1
variables for the duration of a gitsh session.
.Bd -literal -offset indent
@ :set user.name George
@ :set user.email george@thoughtbot.com
@ commit
.Ed
.Pp
See the section on
.Sx VARIABLES
for more information.
.It Ic :echo string ...
prints the given strings to standard output, followed by a newline. All
whitespace is collapsed into one space. This can be useful for viewing
the value of a variable:
.Bd -literal -offset indent
@ :echo $user.name
.Ed
.Pp
Or for a mix of variables and arbitrary strings:
.Bd -literal -offset indent
@ :echo "This is ${user.name}'s work"
.Ed
.It Ic :cd [path]
changes directory to the given path. Without an argument it changes directory
to the repository's root.
.It Ic :help [command]
displays help about the given built-in command. Without an argument it outputs
a list of all built-in commands. When given the name of a command, it outputs a
usage message and brief description of that command.
.It Ic :source path
runs the commands in the given file. Variables
.Ic :set
in the sourced file will remain set after the
.Ic :source
command has finished, making it similar to the
.Ic source
built-in command in
.Xr sh 1
and other Unix shells.
.Bd -literal -offset indent
@ :source /home/george/.gitshrc
.Ed
.It Ic :exit
ends the gitsh session.
.It Ic :q
alias for
.Ic :exit .
.El
.
.Sh VARIABLES
Variables can be read using the
.Ic $
prefix. There are three kinds of variables supported by gitsh:
.Pp
.Bl -enum
.It
Variables set using the
.Ic :set
command.
.Bd -literal -offset indent
@ :set greeting "Hello, world"
@ :echo $greeting
.Ed
.It
All
.Xr git-config 1
settings can be treated as variables in gitsh. For example, the following
commands will produce the same output.
.Bd -literal -offset indent
@ config user.name
@ :echo $user.name
.Ed
.It
There are a number of "magic variables" which expose information about the
current state of the repository.
.Bl -tag -width Ds
.It Ic $_prior
The name of the previous branch that was checked out. This is usually
equivalent to
.Ic @{-1} ,
but will also work in situations where the branch name is required.
.It Ic $_merge_base
When there is a merge in progress, this will be the hash of the merge's base
commit. It is equivalent to the output of
.Ic merge-base HEAD MERGE_HEAD .
.It Ic $_rebase_base
When there is a rebase in progress, this will be the hash of the commit onto
which we are rebasing, for example after running
.Ic rebase master
this variable would evaluate to the hash of the commit at the head of the
.Ic master
branch.
.It Ic $_root
The absolute path to the current repository's root directory. This is
equivalent to the output of
.Ic git-rev-parse --show-toplevel .
.El
.El
.Pp
Attempting to use an unset variable will cause a command to fail. This is
different to
.Xr sh 1 ,
which will ignore unset variable arguments.
.Pp
Magic variables will behave like unset variables when used in a context
where they don't make sense, e.g. using
.Ic $_root
outside of a Git repository.
.Sh SUB-SHELLS
.Pp
Sub-shells can be used to pass the output of any command--including Git
commands, internal commands, and shell commands--as an argument to another
command. A sub-shell is surrounded by
.Ic $(...) .
For example:
.Bd -literal -offset indent
@ :set directory $(!pwd)
.Ed
.Sh COMMAND ARGUMENTS
.Pp
When arguments are passed to Git commands, internal commands, or shell
commands, gitsh will recognise and interpret various methods of quoting
characters. These are similar to those supported by
.Xr sh 1 ,
and other general-purpose shells.
.Pp
In general, a character which would otherwise have some special meaning may
be included as a literal character in an argument if it is prefixed with a
.Ic \e
character.
.Pp
In an
.Em unquoted
argument, the string delimiters
.Pf ( Ic '" Ns ),
the variable or sub-shell prefix
.Pf ( Ic $ Ns ),
parentheses
.Pf ( Ic ( ) Ns ),
and any character which would indicated the end of the argument
(spaces,
.Ic &|;# Ns )
can be escaped.
.Pp
In a
.Em double-quoted
argument, only the string delimiter
.Pf ( Ic \(dq Ns ),
and the variable or sub-shell prefix
.Pf ( Ic $ Ns )
can be escaped.
.Pp
In a
.Em single-quoted
argument, very few characters have special meaning, and so only the
string delimiter
.Pf ( Ic ' Ns )
can be escaped.
.Pp
Line-breaks can be escaped by ending a line with a
.Ic \e
character. This is useful for splitting long commands over multiple lines.
.Pp
A literal
.Ic \e
character can always be produced by repeating it
.Pf ( Ic \e\e Ns ),
but a single
.Ic \e
will also be interpreted as a literal as long as it isn't followed by
a character that can be escaped in the current context.
.Sh CONFIGURATION
The following
.Xr git-config 1
variables can be used to customise the behaviour of gitsh:
.Bl -tag -width Ds
.It Ic gitsh.historyFile
The path to the gitsh history file. The default is
.Ic ~/.gitsh_history
.It Ic gitsh.historySize
The number of lines of history to save in the gitsh history file.
The default is 500.
.It Ic gitsh.prompt
The format of the prompt. See the
.Sx PROMPT
section above for details.
.It Ic gitsh.noGreeting
If this is set to
.Ic true
then no greeting message will be displayed when gitsh starts.
.It Ic gitsh.defaultCommand
The command that will be run when a user presses return without entering any
command. By default this is
.Ic status .
.It Ic gitsh.gitCommand
The command that gitsh will use to run git commands. The default is
.Ic /usr/bin/env git .
.It Ic gitsh.color.*
Various settings are available to customize the colors used in the prompt.
See the
.Sx PROMPT
section above for a list of settings,
and
.Xr git-config 1
for the values that color settings can take.
.El
.Pp
In addition, some standard
.Xr git-config 1
variables modify the behaviour of gitsh:
.Bl -tag -width Ds
.It Ic help.autocorrect
When this is set to anything other than 0, an extraneous
.Ic git
prefix to a command will be automatically removed. This will help users who
are used to using
.Xr git 1
through a general purpose shell.
.El
.
.Sh FILES
.Bl -tag -width Ds
.It Pa $HOME/.gitshrc
A user's personal configuration file. If this file exists, it will be loaded
at the start of interactive sessions, as if it had been passed to the
.Ic :source
command.
.Pp
The
.Pa .gitshrc
file will not be loaded for non-interactive sessions, e.g. when gitsh is
invoked with the path to a script file.
.It Pa @pkgsysconfdir@/completions
System-wide tab completions file, which defines the tab completion options
for popular Git commands.
.Pp
See
.Xr gitsh_completions 5
for details on the format of this file.
.It Pa $HOME/.gitsh_completions
User-defined tab completions file, which can be used to add additional
completion rules, for example to add tab completion support for custom
commands and some aliases.
.Pp
As with the system-wide completions file,
this file uses the format described in
.Xr gitsh_completions 5 .
.It Pa $HOME/.inputrc
gitsh uses
.Xr readline 3
for interactive input, and therefore uses the settings in the user's
.Pa .inputrc
file.
.Pp
Settings can be conditionally loaded by specific applications.
The following example, adapted from the
.Xr readline 3
documentation, demonstrates how to apply a setting only to gitsh:
.Bd -literal -offset indent
$if gitsh
  # Quote the current or previous word
  "\\C-xq": "\\eb\\"\\ef\\""
$endif
.Ed
.El
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev TERM
The
.Xr terminfo 1
name for the terminal. This is used to determine whether to
show colors.
.El
.
.Sh EXAMPLES
.Bd -literal -offset indent
init
commit --allow-empty
checkout -b new-feature
rebase master
:exit
.Ed
.
.Sh SEE ALSO
.Xr gitsh_completions 5
.Xr git 1
.Xr gittutorial 7
.Xr readline 3
.
.Sh HISTORY
Written by
.An "George Brocklehurst" Aq george@thoughtbot.com ,
based on a prototype by
.An "Mike Burns" Aq mburns@thoughtbot.com
from October 2013, inspired by a talk by
.An "Reda Lemeden" Aq reda@thoughtbot.com .
.
.Sh AUTHORS
.An "thoughtbot" Aq hello@thoughtbot.com
